home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_kdelibs.idb / usr / freeware / kde / include / kurl.h.z / kurl.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  11.6 KB  |  363 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 1997 Steffen Hansen (stefh@dit.ou.dk)
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.     Boston, MA 02111-1307, USA.
  18. */
  19. #ifndef KURL_H
  20. #define KURL_H
  21.  
  22. // -*-C++-*-
  23. // KURL header
  24. //
  25.  
  26. #ifdef HAVE_CONFIG_H
  27. #include <config.h>
  28. #endif
  29.  
  30. #include <qstring.h>
  31. #include <qstrlist.h>
  32.  
  33. /** 
  34. * A class for URL processing.
  35. *
  36. * The KURL class deals with uniform resource locators in a 
  37. * protocol independent way. It works on file:-type URLs
  38. * much like @ref QDir does on normal directories; but KURL extends 
  39. * the directory operations to work on general URLs. In fact, the 
  40. * part of KURL that only deals with syntax doesn't care about 
  41. * the protocol at all, so feel free to use it to format any 
  42. * URL-like string. 
  43. * 
  44. * NOTE: KURL doesn't support URL's that don't look like files 
  45. * (for example mailto:someone@somewhere). [If URL's like this were OK, 
  46. * there would be no reason for isMalformed() since any string with a 
  47. * ":" would be a valid URL.  Comments please.] 
  48. *
  49. * First version by Torben Weis, redesigned by Steffen Hansen (stefh@mip.ou.dk),
  50. * maintained by Torben Weis (weis@kde.org). Endcoding/Decoding done by
  51. * Stephan Kulow (coolo@kde.org).
  52. *
  53. * @author Torben Weis (weis@kde.org)
  54. *
  55. * @version $Id: kurl.h,v 1.17 1998/06/07 12:31:26 kulow Exp $
  56. * @short A class for URL processing.
  57. */
  58.  
  59. class KURL
  60. { 
  61. public:
  62.  
  63.     /** 
  64.      * Construct a KURL object.
  65.      */
  66.     KURL();
  67.     
  68.     /** 
  69.      * Construct a KURL object from _url. 
  70.      *
  71.      * A KURL object is always constructed, but if you plan to use it, 
  72.      * you should check it with isMalformed().
  73.      *
  74.      * if the parameter is an absolute filename, it adds a file: prefix 
  75.      * and encodes the path.
  76.      */
  77.     KURL( const char* _url);
  78.  
  79.     ~KURL();
  80.  
  81.     /** 
  82.      * Construct a KURL object from its components. 
  83.      */
  84.     KURL( const char* _protocol, const char* _host, 
  85.       const char* _path, const char* _ref);
  86.     
  87.     /**
  88.      * Constructs a URL.
  89.      *
  90.      * The second argument may be a relative URL, like '/home/weis/test.txt'.
  91.      * If for example the first parameter is 'http://uni-frankfurt/pub/incoming' 
  92.      * then the result will be 'http://uni-frankfurt/home/weis/test.txt'. 
  93.      *
  94.      * Of course the second argument may be a complete URL, too.
  95.      */
  96.     KURL( KURL & _base_url, const char* _rel_url );
  97.     
  98.     /** 
  99.      * Returns true if the URL is not a valid URL. This is only syntax-checking;
  100.      * whether the resource to which the URL points exists is not checked.
  101.      *       
  102.      * NOTE: Syntax checking is only done when constructing a KURL from a string. 
  103.      */
  104.     bool isMalformed() const { return malformed; }
  105.     
  106.     /**
  107.      * Escapes some reserved characters within URLs (e.g. '#', '%').
  108.      *
  109.      * Some characters in filenames or directory names make troubles
  110.      * For example '#' or '%' makes problem, if they are interpreted
  111.      * and not ment to be interpreted. This why we must encode them.
  112.      * This functions encodes the given URL and returns a reference
  113.      * to the result for convidence.
  114.      */
  115.     static void encodeURL( QString& url );
  116.     
  117.     /**
  118.      * Decodes escaped characters within URLs.
  119.      *
  120.      * This function looks for '%' within the URL and replaces this character 
  121.      * with hexcode of the next two characters. If the next characters are not 
  122.      * hex chararcters, 0 will be used and the character will be skipped.
  123.      */
  124.     static void decodeURL( QString& url );
  125.     
  126.     /** 
  127.      * Returns the URL as a QString.
  128.      */
  129.     QString url() const;
  130.     
  131.     /** 
  132.      * The function returns the protocolname up to, but not including the ":".
  133.      */
  134.     const char* protocol() const;
  135.     
  136.     /** 
  137.      * This function returns the host. If there is no host (i.e.
  138.      * the URL refers to a local file) this function returns "".
  139.      */
  140.     const char* host() const;
  141.     
  142.     /** 
  143.      * This function returns the path-part of the URL.
  144.      *
  145.      * For example, path() on "tar://ftp.foo.org/bar/stuff.tar.gz#tex/doc.tex" 
  146.      * returns "/bar/stuff.tar.gz".
  147.      */
  148.     const char* path() const;
  149.     
  150.     /**
  151.      * If we parse for example ftp://weis@localhost then we dont have a path.
  152.      * The URL means: enter the home directory of user weis, while
  153.      * ftp://weis@localhost/ means, login as user weis and enter the
  154.      * root directory. KURL returns "/" as path in both cases. This function
  155.      * lets you distinguish both URLs. It returns true in the first case.
  156.      *
  157.      * @see #bNoPath
  158.      */
  159.     bool hasPath() const { return !bNoPath; }
  160.     
  161.     /** 
  162.      * This function returns the reference. 
  163.      *
  164.      * If the URL is "http://www.nowhere/path/file.html#toc", this function 
  165.      * will return "toc". If there is no reference it returns "".
  166.      * If we have some subprotocol in the URL like in 
  167.      * file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section
  168.      * then only the last reference is going to be returned, in this case
  169.      * "section". A URL like
  170.      * file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html
  171.      * would return "" since there is no reference. The stuff behind
  172.      * the '#' is a subprotocol!
  173.      */
  174.     const char* reference() const;
  175.     
  176.     /**
  177.      * This function returns the user name or an empty string if
  178.      * no user has been specified.
  179.      */
  180.     const char* user();
  181.     
  182.     /**
  183.      * The password.
  184.      *
  185.      * @return the password, or an empty string if no password was specified.
  186.      */
  187.     const char* passwd();
  188.     
  189.     /**
  190.      * The port number.
  191.      *
  192.      * @return the port number, or 0 if none was specified.
  193.      */
  194.     unsigned int port() const;
  195.     
  196.     /**
  197.      * Returns the directory only.
  198.      *
  199.      * If for example the URL is "file:/tmp/weis/file.html", then this call
  200.      * will return "/tmp/weis/". If you pass "file:/tmp/weis/" to this
  201.      * function, you will get "/tmp/weis/", because you already passed a directory.
  202.      * Turning the '_trailing' flag off, causes the trailing '/' to be ignored.
  203.      * "file:/tmp/weis/file.html" will result in "/tmp/weis/", too, but
  204.      * "file:/tmp/weis/" will lead to "/tmp/". As you see, this is
  205.      * a smart method to get the parent directory of a file/directory.
  206.      *
  207.      * This function is supplied for convenience only.
  208.      */
  209.     const char * directory( bool _trailing = TRUE );
  210.     
  211.     /**
  212.      * Returns the URL with the directory only.
  213.      *
  214.      * If for example the URL is "file:/tmp/weis/file.html", then this call
  215.      * will return "file:/tmp/weis/". For more details look at 'directory(...)'
  216.      */
  217.     const char * directoryURL( bool _trailing = TRUE );
  218.     
  219.     /**
  220.      * @return TRUE if the URL has a sub protocol. For example file:/tmp/kde.tgz#tar:/kfm/main.cpp
  221.      *         is a URL with subprotocol. Use this function to check wether some URL really
  222.      *         references a complete file on your local hard disk and not some special data
  223.      *         inside the file, like the example shows.
  224.      */
  225.     bool hasSubProtocol();
  226.  
  227.     /**
  228.      * If the URL has no subprotocol, parentURL behaves like a call to @ref #url.
  229.      * Otherwise the part of the URL left to the last subprotocol is returned.
  230.      * For example file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section will return
  231.      * file:/tmp/kde.tgz#tar:/kfm.rpm. As you can see, the last subprotocol is stripped.
  232.      * If the original URL is for example file:/httpd/index.html#section
  233.      * then exact this string is going to be returned.
  234.      */
  235.     QString parentURL();
  236.     /**
  237.      * This call returnes the other part of the URL, the part that is stripped by @ref #parentURL.
  238.      * It returns always the right most subprotocol. If there is no subprotocol, the call
  239.      * to this function returns an empty string. For example a URL 
  240.      * file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section
  241.      * would return rpm:/doc/index.html#section.
  242.      */
  243.     QString childURL();
  244.     /**
  245.      * This function behaves like @ref #childURL, but if there is no subprotocol,
  246.      * this function returns the same @ref #url returns instead of an empty string.
  247.      */
  248.     QString nestedURL();
  249.  
  250.     /**
  251.      * Parse a string.
  252.      */
  253.     void parse( const char *_url );
  254.     
  255.     /** 
  256.      * Sets the protocol to newProto. Useful for example if an app hits
  257.      * "file:/tmp/interesting.zip", then it might do setProtocol( "zip").
  258.      */ 
  259.     void setProtocol( const char* newProto) ;
  260.     
  261.     /**
  262.      * Set the password.
  263.      */
  264.     void setPassword( const char *password );
  265.     
  266.     /** 
  267.      * Set reference. 
  268.      *
  269.      * A reference may be removed with setRef( ""). The function returns false 
  270.      * if it could not make a reference (if there were no path to reference 
  271.      * from) and true on succes.
  272.      */
  273.     bool setReference( const char* _ref);
  274.  
  275.     /** 
  276.      * Changes directory by descending into the given directory. 
  277.      * If dir starts with a "/" the 
  278.      * current URL will be "protocol://host/dir" otherwise dir will 
  279.      * be appended to the path.
  280.      * If 'zapRef' is true, the reference will be deleted.
  281.      */   
  282.     bool cd( const char* _dir, bool zapRef = true);
  283.     
  284.     /** 
  285.      * Go to parent dir. If zapRef is true, the reference is removed, 
  286.      * otherwise it stays, but normally no one would want that. 
  287.      */
  288.     bool cdUp( bool zapRef = true);
  289.     
  290.     /**
  291.      * Returns the filename or directory name of the URL.
  292.      *
  293.      * If 'file:/home/weis/test.txt' is the URL, the result will be 'test.txt'
  294.      * If the URL us 'tar:/home/weis/test.tgz#foo/myfile' and isReference is TRUE,
  295.      * the function will return 'myfile'
  296.      */
  297.     const char *filename();
  298.     
  299.     /**
  300.      * Makes a copy of a URL.
  301.      */
  302.     KURL &operator=( const KURL &);
  303.     
  304.     /** 
  305.      * Initialize the URL with the given string.
  306.      * '_url' must be a valid URL.
  307.      */
  308.     KURL &operator=( const char* _url );
  309.     
  310.     /** 
  311.      * Compare URL's.
  312.      *
  313.      * @return true if the URLs are equal, false otherwise.
  314.      */
  315.     bool operator==( const KURL &_url) const ;
  316.  
  317.  
  318.     /**
  319.       * Checks, if the URL refers to a usual file, that
  320.       * can be openend with usual methods.
  321.       *
  322.       * Note: It doesn't check, if the file exist
  323.       *
  324.       * @return true, if the URL is a file, that can be opened
  325.       **/
  326.     bool isLocalFile();
  327.  
  328. protected:
  329.     void cleanPath();
  330.     
  331.     bool malformed;
  332.     /**
  333.      * If we parse for example ftp://weis@localhost then we dont have a path.
  334.      * The URL means: enter the home directory of user weis, while
  335.      * ftp://weis@localhost/ means, login as user weis and enter the
  336.      * root directory. KURL returns "/" as path in both cases. This variable
  337.      * is used to distinguish both URLs. It is true in the first case.
  338.      *
  339.      * @see #hasPath
  340.      */
  341.     bool bNoPath;
  342.     int port_number; 
  343.  
  344.     QString protocol_part;
  345.     QString host_part;
  346.     QString path_part;
  347.     QString path_part_decoded;
  348.     QString ref_part;
  349.     // This variable is only valid after calling 'directory'.
  350.     QString dir_part;
  351.     QString user_part;
  352.     QString passwd_part;
  353.     
  354. private:
  355.     void detach();
  356. };
  357.  
  358.  
  359.  
  360. #endif
  361.  
  362.  
  363.